******************************************************************
* Document type: Library reference
* Readme file name: manmpg.txt
* Library prefix: MPG
* Library name: MPEG
* Version: 1.24
* Creator: H.T.
* Created: 2/01/96
* Comments: None
******************************************************************

1. History of Changes

1.1 Changes from Ver.0.90 to Ver.0.95
(1) Removal of the MPG_WnSetTrBuf function
Use the MPG_WnSetOutputMode function for changes to the host
transfer area.

(2) Changes to function values
For the following functions, specifications were changed so that
an error code is returned as the function value.
* MPG_Init
* MPG_MvStart    * MPG_MvOutput    * MPG_MvChange
* MPG_SpStart    * MPG_SpOutput

(3) Changes to argument types
The following arguments were changed from Sint32 to Bool type.
* MPG_MvStart function picsch
* MPG_MvSetPan function lsw, rsw
* MPG_WnSetIntpol function sw_yh, sw_yv, sw_ch, sw_cv
* MPG_WnSetSoft function sof_h, sof_v
* MPG_WnSetLumiKey function bdr

(4) Other
(a) MPG_GetReport function was added.
(b) MPG_MvSetLay function was added.
(c) MPG_MvOutput function specification was changed.  (Argument
chkupic was added.)
(d) The MPEG check has been set to be performed in the MPG_Init
function.
(e) Set so that the decoder is initialized if the MPG_MvStop
function is called during restore processing.

1.2 Changes from Ver.0.95 to Ver.1.00
(1) Changes to function names
Function names were changed as follows.
* MPG_MvDecodeNext -> MPG_MvDecNext
* MPG_SpDecode -> MPG_SpDecNext

(2) Other
(a) The MPG_IsDecReady function was added
(b) The MPG_GetInt function was added
(c) Resolved nonconformities when the MPG_CaptStat function is
called by interrupt

1.3 Changes from Ver.1.00 to Ver.1.20
(1) Operation changes to the MPG_Init function
The CD block software reset was set to be performed in the
function, so this function must be called before the GFS_Init
function and STM_Init function.

(2) Operation changes to the MPG_MvStop function
The MPG_MvStop function operation during audio/video synchronous
playback was changed in the following manner.
(a) Stops audio.
(b) Confirms audio stop.
(c) Stops video.

(3) Specification changes to the MPG_IsDecReady function
The MPG_DCPIC_FST and MPG_DCPIC_NXT constants were removed, and
MPG_HDEC_PRE and MPG_HDEC_EXE were added.

(4) Changes to constant names
Constant names were changed as follows.
* MPG_FREEZE_STOROBO -> MPG_FREEZE_STRB
* MPG_TERMCOND_NOTHING -> MPG_TCND_NONE
* MPG_TERMCOND_EOR -> MPG_TCND_EOR
* MPG_TERMCOND_SYSEND -> MPG_TCND_SEC
* MPG_ACLR_NOTHING -> MPG_ACLR_NONE

(6) Other
(a) The MPG_ResetMp function was added.
(b) The MPG_MvStopVideo and MPG_MvStopAudio functions were added.
(c) The function value of the MPG_MvGetPlaytime function was set
in milliseconds.
(d) Made compatible with CDC library Ver.1.20

1.4 Changes from Ver.1.20 to Ver.1.21
(1) Changes to the operation of getting the cause of MPEG
interrupt
The cause of MPEG interrupt is only gotten when the MPST flag is
on in the MPG_IsDecReady and MPG_CheckHng functions.

(2) Changes to settings of the MPEG interrupt mask
Set so the picture start detection and sequence end detection
interrupt mask is canceled immediately after initializing the MPEG
decoder.

(3) Changes to the MPG_WnSetDispRatio function specifications
The upper limit for the scaling factor was (352000, 240000), but
this limit was eliminated.

(4) PAL compatibility (MPG_Init function)
(a) Operation changes
Changed so that when PAL values were set in the scan mode, the
display window offset in the function is (150, 45).
(b) Addition of scan mode PAL constant names
* MPG_DSCN_PLNITL         /* PAL non-interlace mode */
* MPG_DSCN_PLITL          /* PAL interlace mode */

(5) Changes to playback stop function operation
(a) VBV buffer clear is set to be performed in the MPG_MvStop
function, MPG_MvStopVideo function, and MPG_SpStop function.
(b) Set so that the next stream of the MPEG system is erased when
animation playback is stopped.

(6) Other
(a) The function name MPG_WnSetYCratio was changed to
MPG_WnSetYcRatio.
(b) Set so that when using a default transfer function for the
host transfer mode, a time-out of approximately 2 seconds occurs
when the SCU DMA transfer does not end.

1.5 Changes from Ver.1.21 to Ver.1.22

(1) The addition of error codes
The following error codes have been added:
*MPG_ERR_NOTENTRY       the next animation has not been entered
*MPG_ERR_ENTERYNG       entry of the next animation was
                        unsuccessful

(2) Changes in function values
The function values of the following functions have been changed
from void to Sint32-type error code:
*MPG_SetVideoMode
*MPG_MvDestroy     *MPG_MvDecNext     *MPG_MvEntryNext
*MPG_SpDestroy     *MPG_SpStop        *MPG_SpDecNext
*MPG_WnTrans

(3) Specification changes in the user transfer function
The function value for the user transfer function has been changed
from void to a Sint32-type error code.

1.6 Changes from Ver.1.22 to Ver.1.23
(1) Corrected problems with the stop function for animation
playback.  When the animation was stopped using the MPG_MvStop function, the
When the animation was stopped using the MPG_MvStop function, the
audio portion stopped, however, the video continued to play.This
problem has been corrected.

1.7 Changes from Ver.1.23 to Ver.1.24
(1) Addition of error codes
(a) The following error codes have been added:
*MPG_ERR_ILLHDL         an illegal handle has been used
*MPG_ERR_CREATE         unsuccessful in creating a handle
*MPG_ERR_GETTC          unsuccessful in fetching the time code
*MPG_ERR_DESTROY        unsuccessful in deleting the handle
*MPG_ERR_WAIT           the MPEG command is in a WAIT state

(b) The following error code has been changed
*MPG_ERRNOTENTRY -> MPG_ERR_ILLSTAT  the handle is not operational

(2) The addition of error functions
The MPG_GerErrStat and MPG_SetErrFunc functions have been added.

(3) Preventing double access of the static variable
When a decoder was initialized in the play stop function and the
MPG_CaptStat function was called, there was a possibility for
double access to the static variable. To prevent this problem,
there is a period of time when no interrupts are allowed.

(4) An added process when a decoder is initialized in the play
stop function. When the decoder is initialized, the MPEG screen display
is turned off. This display can now be turned ON from the library.

(5) Bug fixes
The problem of the MPEG handle returning an incorrect value has
been corrected so that it returns the value 0. This occurred when
the MPG_MvGetTimeCode function was called while the MPEG handle
was in the preparation state (immediately after play is started).

2. Additional manual documents

2.1 User transfer function
The function value has been changed to an error code (Ver.1.22 or
later). A time out has been added in the default transfer function
(Ver.1.21). The new specifications are as follows:

Format:          Sint32 trFunc(void *dst, void *src, Sint32 nbyte)
Input:
dst :            transfer source address
src :            transfer destination address
nbyte :          number of transfer bytes
Function value:  error code

(a) The transfer area address that is set in the
MPGWnSetOutputMode function is placed in dst.
(b) The transfer function is called from the MPEG library when
MPG_WnTrans function is executed.
(c) Use the MPG_WnEntryTrFunc function to enter the transfer
function.
(d) The DMA transfer function by SCU to the B-Bus is entered as
the default of the transfer function.
(e) The default transfer function will time out if the DMA
transfer is not done in approximately 2 seconds.

2.2 Data specification
(1) Error codes
The error codes have been changed as follows:

+----------------+----------------+-------------------+-----+
| Title          | Data           | Data     Name     | No. |
|                |                |                   |     |
| Data Specs     | Error code     |                   | 2.0 |
+----------------+----------------+-------------------+-----+

The value of MPG_ERR_OK is 0.  All other error codes are negative
values.

+--------------------+------------------------------------------+
| Constant name      | Description                              |
+--------------------+------------------------------------------+
| MPG_ERR_OK         | Normal exit                              |
+--------------------+------------------------------------------+
| MPG_ERR_CDINIT     | CD block initialization was unsuccessful |
+--------------------+------------------------------------------+
| MPG_ERR_NOMC       | No MPEG cartridge                        |
+--------------------+------------------------------------------+
| MPG_ERR_MPNG       | MPEG check unsuccessful                  |
+--------------------+------------------------------------------+
| MPG_ERR_MPINIT     | Initialization of MPEG decoder           |
|                    | unsuccessful                             |
+--------------------+------------------------------------------+
| MPG_ERR_TMOUT      | Time out                                 |
+--------------------+------------------------------------------+
| MPG_ERR_PLAYING    | Playing another MPEG stream              |
+--------------------+------------------------------------------+
| MPG_ERR_MCON       | MPEG decoder connection unsuccessful     |
+--------------------+------------------------------------------+
| MPG_ERR_RCU        |                                          |
+--------------------+------------------------------------------+
| MPG_ERR_CHG        | Stopped during switching                 |
+--------------------+------------------------------------------+
| MPG_ERR_ILLSTAT    | The handle is not in an operational state|
+--------------------+------------------------------------------+
| MPG_ERR_ENTRYING   | Entry of the next animation unsuccessful |
+--------------------+------------------------------------------+
| MPG_ERR_ILLHDL     | Use of an illegal handle                 |
+--------------------+------------------------------------------+
| MPG_ERR_CREATE     | Not successful at creating a handle      |
+--------------------+------------------------------------------+
| MPG_ERR_GETTC      | Not successful at fetching the time code |
+--------------------+------------------------------------------+
| MPG_ERR_DESTROY    | Not successful at deleting a handle      |
+--------------------+------------------------------------------+
| MPG_ERR_WAIT       | The execution of the MPEG command is on  |
|                    | hold                                     |
+--------------------+------------------------------------------+
| MPG_ERR_NG         | Other abnormal end                       |
+--------------------+------------------------------------------+

(2) Addition of data type
The following data types have been added.

+----------------+----------------+-------------------+-----+
| Title          | Data           | Data Name         | No. |
|                |                |                   |     |
| Data Specs     | Error function | MpgErrFunc        | 3.5 |
+----------------+----------------+-------------------+-----+

Format:         void (*MpgErrFunc)(void *obj, Sint32 errcode)
Input:
           obj: entered object
       errcode: error code
Output:         none
Description:    This data type describes the error function that is
                called during an error. Use the MPG_SetErrFunc to
                enter an error function.

+----------------+----------------+-------------------+-----+
| Title          | Data           | Data Name         | No. |
|                |                |                   |     |
| Data Specs     | Error status   | MpgErrStat        | 3.6 |
+----------------+----------------+-------------------+-----+

This is data that is output by the MPG_GetErrStat function.

MpgErrStat *stat

+--------------------+------------+--------------------------+
| Access macro       | Type       | Description              |
+--------------------+------------+--------------------------+
| MPG_ERR_FUNC(err)  | MpgErrFunc | A pointer to the error   |
|                    |            | function                 |
+--------------------+------------+--------------------------+
| MPG_ERR_OBJ(err)   | void*      | 1st argument for the     |
|                    |            | error function           |
+--------------------+------------+--------------------------+
| MPG_ERR_CODE(err)  | Sint32     | Error code               |
+--------------------+------------+--------------------------+

2.3 Function specifications

(1) Added functions
The following functions have been added.

+----------------+-----------------------+-----------------+-----+
| Title          | Function              | Function Name   | No. |
|                |                       |                 |     |
| Function Specs | Fetch error status    | MPG_GetErrStat  |1.11 |
+----------------+-----------------------+-----------------+-----+
Format:         Sint32 MPG_GetErrStat(MpgErrStat *stat)
Input:          none
Output:   stat: error status
Function Value: error code
Function:       Fetches the error status of the library function
                last executed.

+----------------+-----------------------+-----------------+-----+
| Title          | Function              | Function Name   | No. |
|                |                       |                 |     |
| Function Specs | Enter error function  | MPG_SetErrFunc  |1.12 |
+----------------+-----------------------+-----------------+-----+
Format:         void MPG_SetErrFunc(MpgErrFunc func, void *obj)
Input:    func: the function called when error results
Output:    obj: entered object
Function value: none
Function:       Sets the function called when there is an error.
                The entered object is sent to the first argument
                of the error function.

(2) Function name changed
(a) MPG_WnSetYCratio --> MPG_WnSetYcRatio

(3) Function of MPG_LsDecReady function changed
"Waiting for start of decode" --> "Checking for completion of
decode preparation".

(4) Function value changes
The function values of the following functions have been changed
from void to Sint32-type error codes:

*MPG_SetVideoMode
*MPG_MvDestroy   *MPG_MvDecNext   *MPG_MvEntryNext
*MPG_SpDestroy   *MPG_SpStop      *MPG_SpDecNext
*MPG_WnTrans

(5) MPG_Init function
The function and notes have been changed as below:

[Function]
Initializes the MPEG system.  The MPEG audio can be played back
once the initialization is done.
This function must be called first before using the MPEG library.
(1) Display scan method
*MPG_DSCN_NITL : NTSC non-interlace mode
*MPG_DSCN_ITL : NTSC non-interlace mode
*MPG_DSCN_PLNITL : PAL non-interlace mode
*MPG_DSCN_PLITL : PAL interlace mode

[Notes}
(a) The following is executed within the function and an error
code is returned.

+---+----------------------------------+-------------------------+
|   |      Procedure                   |     Error code          |
+---+----------------------------------+-------------------------+
| 1 |Soft resets the CD block          | Returns MPG_ERR_CDINIT  |
|   |(CDC_CdInit function)             | for an error            |
+---+----------------------------------+-------------------------+
| 2 |Uses CDC_GetHwInfo to check       | If not installed, return|
|   |whether the MPEG cartridge is     | MPG_ERR_NOMC            |
|   |installed or not                  |                         |
+---+----------------------------------+-------------------------+
| 3 |Executes MPEG check (SYS_CHKMPEG) | If the check is not     |
|   |by the boot rom service routine   | successful, return      |
|   |when MPEG cannot be used          | MPG_ERR_MPNG            |
+---+----------------------------------+-------------------------+
| 4 |Execute MPEG decoder              | Return MPG_ERR_MPINIT   |
|   |initialization (CDC_Mpinit)       | if error results        |
+---+----------------------------------+-------------------------+
| 5 |Sets the MPEG interrupt mask      | Return MPG_ERR_NG if    |
|   |and allows picture start search   | error results           |
|   |and sequence end search           |                         |
|   |interrupt                         |                         |
+---+----------------------------------+-------------------------+
| 6 |Sets the display window offset    | Return MPG_ERR_NG if    |
|   |to (150,45) using CDC_MpSetWinDofs| error results           |
|   |if a constant is specified for the|                         |
|   |display scan method               |                         |
+---+----------------------------------+-------------------------+

(6) MPG_MvDestroy function
The following [Notes] has been added.
(a) Both the audio and video must be stopped for the handle.
(b) A handle may not be entered as the next handle to playback by
the MPG_MvEntryNext function.
(c) This function executes the stop playback function.

(7) MPG_SpDestroy function
The following have been added to [Notes]
(a) The video must be stopped for the handle.
(b) This function executes the stop playback function.

(8) MPG_MvGetVideoStat function
The following has been added to [Function].
*MPG_VSTAT_ERR:  error

(9) MPG_MvGetAudioStat function
The following has been added to [Function].
*MPG_ASTAT_ERR:  error

(10) MPG_SpGetVideoStat function
The following has been added to [Function].
*<{G_SSTAT_ERR:  error

2.4 Play stop function
(1) Changes in the MPG_MvStop function (Ver. 1.20 and later)
The MPG_MvStop function during audio/video playback has been
modified as below:
(a) Stops the audio.
(b) Checks that the audio is stopped.
(c) Stops the video.

(2) Changes in the play stop function
(a) In previous versions, the MPEG screen display was turned off
when the decoder was initialized in the play stop function. The
display can be turned on from the library for Ver.1.24.  For all
versions before Ver.1.23, the user must use the MPG_MvDisp
function to turn the display on.
(b) The VBV buffer is cleared in the MPG_MvStop, MPG_MvStopVideo,
MPG_SpStop functions. (Ver.1.21 or later)
(c) ----when the animation is stopped. (Ver.1.21 or later)
(d) When a decoder was initialized in the play stop function and
the MPG_CaptStat function was called, there was a possibility for
double access to the static variable. To prevent this problem,
there is a period of time when no interrupts are allowed.(Ver.1.24
or later)

2.5 MPG_MvEntryNext function
(1) Restrictions
(a) Do not enter MPEG animation handles that play different
streams. For example, do not enter an animation handle for video
play only after a handle for audio/video simultaneous playback.
(b) Do not set the following when switching the animation.  The
settings before switching is used after switching.
*video and audio channel
*video stream ID and audio stream ID
*the slow play speed
*strobe distance
*the right and left channels for sound.

3. Precautions for use
(1) MPCM flag status
Be sure the MPCM flag is ON when calling functions from this
library.

(2) Liminations of the MPST flag
The normal function of the following are not guaranteed after the
MPST flag is cleared or when the MPEG interrupt mask settings are
made in the application.
*MPG_IsDecReady
*MPG_CheckHng

(3) How to modify the display window offset
Use the CDC_MpSetWinDofs function of the CD communication
interface to change the display window offset in the application.

(4) Limitations on the default transfer function in the host
transfer mode
The MPEG library uses the DMA library to start up the SCU-DMA when
the default transfer function is used. Level 0 is used.
Therefore, the INT_ChgMsk function must be executed to permit a
level0-DMA interrupt as shown below. (Refer to the document on
DMA/interrupt for further details.)

/* Permit SCU-DMA0 end interrupt */
INT_ChgMsk(INT_MSK_DMAO, INT_MSK_NULL);

The above is executed in the GFS_Init function int he file system
library (Ver.1.11 or later). Therefore, it is not normally
necessary to execute it in the application.

(5) Precautions when using the SCU-DMA
The use of any MPEG library function is prohibited sinceA-Bus
access is not allowed during SCU-DMA transfer. Note that the
default transfer function also uses the SCU-DMA.

(6) Calling a function during an interrupt
MPEG library functions other than MPG_CaptStat may not be used in
an interrupt.

3. Cautions On Use
(1) MPCM flag status
When calling the functions of this library, call with the MPCM
flag on.

(2) Restrictions on use of the MPST flag
When MPST flag clear or MPEG interrupt mask setting is done with
an application, operation of the following functions is not
guaranteed.
* MPG_IsDecReady
* EMPG_CheckHng

(3) How to change display window offset
When changing the display window offset with an application, use
the CD communication interface CDC_MpSetWinDofs function.

(4) Restrictions on using default transfer functions for the host
transfer mode
When using the default transfer function, the MPEG library uses
the DMA library to activate SCU-DMA.  The level used is 0.

Therefore, it is necessary to execute the INT_ChgMsk function in
the following manner, and to allow level 0-DMA interrupt.  (For
detailed information, see documents relating to DMA and
interrupt.)

/* Allow SCU-DMA0 completion interrupt */
INT_ChgMsk(INT_MSK_DMA0, INT_MSK_NULL);

This process is executed in the GFS_Init function of the file
system library (Ver.1.11), so it is normally not necessary to
execute using an application.

(5) Cautions when using SCU-DMA
A-Bus access is prohibited during SCU-DMA transfer, so use of any
MPEG library functions is prohibited.  Caution is necessary
because the default transfer function also uses SCU-DMA.

(6) Function calls during interrupts

The use of MPEG functions other than MPG_CaptStat during interrupt
processing is prohibited.

***************************end of file***************************
